Celestin Apprentice 4/Apprentice-Release4.iso/Languages/Chipmunk Basic 3.2.8/basic.man

Text File | 1995-12-12 | 22KB | 823 lines

    BASIC(1)        chipmunk-basic v3.2             BASIC(1)


    Chipmunk BASIC - 'BASIC' language interpreter


    SYNOPSIS    ( UNIX )

    basic [ filename ]

    DESCRIPTION

    Chipmunk basic is an interpreter for the BASIC language. If a
    filename parameter is given, then the named program file is
    loaded and run as a Basic program.

    Basic commands and statements can be entered and interpreted in
    immediate mode or executed as program statements when the Basic
    program is run.  A built-in line number based editor allows
    program input from the console keyboard.  See below for the
    commands the interpreter recognizes.

    FLAGS

    none

    COMMANDS

    Standard mumbleSoft-like Basic Commands:

    load STRINGEXPR

        Load a program into memory from the named file. The
        program previously in memory is erased.  All
        variables are cleared.  All lines in the file must
        begin with a line number.  Line numbers do not
        need to be in increasing order.


    save STRINGEXPR

        Save the current program to a named file.

    new

        Erase the program in memory.  All files are closed and
        all variables are cleared.

    clear

        All  variables are cleared.  All arrays and string
        variables are deallocated.

    run { LINENUM }
    run { STRINGEXPR { , LINENUM } }

        Begin execution of the program at the first line, or at
        the specified line.  All variables are cleared.  If a
        STRINGEXPR is given then the BASIC program with that name
        file is loaded into memory first.  Program lines are
        executed in line number order.

    cont

        CONTinue execution of the program on the next statement
        after the statement on which the program stopped execution
        due to a STOP command or an error.  See BUGS section.

    goto LINENUM

        This statement will transfer control to the line number
        specified.  If the program is not running, then this
        command will begin execution at the specified line
        without clearing the variables.  An "Undefined line"
        error will occur if LINENUM doesn't exist in the program.

    list
        List the whole program.

    list 1-3
        List lines 1 to 2

    list -2
        List lines up to 1

    list 1
        List line 1

    list 2-
        List lines from 2 on

    merge STRINGEXPR

        Load a program into memory.  The previous program
        remains in memory; if a line exists in both programs,
        the newly loaded line is kept.

    renum STRINGEXPR VAL { , VAL { , VAL { , VAL} } }

        Renumber program lines.  By default, the new sequence
        is 10,20,30,... The first argument is a new initial
        line number; the second argument is the increment
        between line numbers. The third and fourth arguments,
        if present, specify a limiting range of old line numbers
        to renumber.  RENUM can be used to move non-overlapping
        blocks of code.

    edit LINENUM

        Edit a single line. If the exit from the edit is via a
        cntrl-c then do not change the line.
            i    insert till <return>
            x    delete one char
            A    append to end of line

    del LINENUM [ - LINENUM ]

        Delete a line or specified range of lines. If not found
        then no lines will be deleted.

    exit
    bye
    quit

        Terminates the basic interpreter, ending program
        execution and closing all files.


    STATEMENTS

    { let } VAR = EXPR

        Assign a value to a variable.  Variable names can be up
        to 31 significant characters, consisting of letters,
        digits, underscores, and an ending dollar sign.
        Variable names are case insensitive.  Variables can
        hold real numbers (IEEE double) or strings of up
        to 254 characters.  If the variable name ends with a
        "$" it holds strings, otherwise it holds numbers.  If a
        statement starts with a variable name then an implied
        LET is assumed.

    print or '?' VAL | STRINGVAL { [ , | ; ] VAL ... } { ; }
    print #FNUM, VAL ...

        This command will print its parameters tab delimited.
        If a semi-colon is used between parameters then no tab
        is inserted between the parameters.  The print
        output is terminated with a carriage return unless the
        parameter list ends with a semi-colon.  If a file
        descriptor is given then output is redirected to the
        given file.  If a

            tab(VAL);

        is found in a print statement, then print output will
        skip to the horizontal position specified by VAL.

    print { #FNUM, } using STRINGVAL ; VAR { [ , | ; ] VAR ... }

        Prints formatted numbers.  Legal characters for the
        format string are: + * $ # . and trailing spaces.

        Examples:

            print using "**$###.##"; 1.23    ->  ****$1.23
            print using "###.##"; 2.12345    ->    2.12


    input { # FNUM , } { STRINGVAR | VAR { , VAR } }

    input "prompt"; { STRINGVAR | VAR  { , VAR } }

        Input from a terminal or from a file. If the input is
        from the terminal then a prompt message can also be
        added.

        All input to string variables is "line input"; a whole
        input line will be read into one string variable.  This
        usage is different from other versions Basic.

    get STRINGVAR

        Gets one character from the console keyboard.  Blocking.

    cls
        Clear the terminals screen.  Leaves the cursor in the
        upper left corner.  For Applesoft BASIC fans, the "home"
        command will also do this.

    end

        Terminates program execution and returns to the command
        prompt.  Not required.

    stop

        Stops the execution of the program and returns to
        the command prompt.  Prints a "Break..." message.

    if EXPR then STATEMENT { : STATEMENT } { : else STATEMENT }
    if EXPR then LINENUM
    if EXPR

        The IF statement.  If the condition is true then the
        STATEMENTS after the THEN are executed and the
        statements after the ELSE are skipped.  If the
        condition is false then the statements after the "else"
        are executed instead.  If the item after "then" is a
        line number then a goto is executed.

        If the condition is true and there is no THEN on the
        same line, statements are executed until a line
        with an ENDIF is found.  (block IF() ... ENDIF)

    for VAR = EXPR to EXPR { step EXPR }

        Beginning of a "for next" loop.  It takes a starting
        value, a limit and an optional step argument.  If the
        step value is negative, the variable counts down.  The
        body of the loop is not executed if the end condition
        is true initially.

        Example:
            for i=1 to 10 : print i, : next i
            rem prints the numbers from 1 through 10

    next { VAR }

        End of a "for next" loop.  If the termination
        conditions are met then execution falls through to the
        following statement, otherwise execution returns to the
        statement following the corresponding "for" statement.
        The "next" does not need a variable name parameter.  If
        this is the case the innermost "for" loop is used.

    while { EXPR }

        Start of a WHILE loop. The loop is repeated until EXPR
        is false. If EXPR is false at loop entry, then the loop
        is not executed at all. A WHILE loop must be
        terminated by a WEND statement.

    wend { EXPR }

        Terminating statement of a WHILE loop.  If EXPR is true
        then exit the loop.  Only one WEND is allowed for each
        WHILE.  A WHILE-WEND loop without a condition will loop
        forever.

    gosub LINENUM

        Transfer command to a line number. Save return address
        so that the program can resume execution at the
        statement after the "gosub" command.  The recursion
        depth is limited only by available memory.

    return

        Returns from the most recently activated subroutine
        call (must have been called by gosub).

    on EXPR   goto  LINENUM { , LINENUM ... }
    on EXPR   gosub LINENUM { , LINENUM ... }
    on error goto  LINENUM

        This command will execute either a goto or a gosub to
        the specified line number indexed by the value of EXPR.

        If the error form is used, only one linenumber is
        allowed.  LINENUM is the line to which control is
        transferred if an error occurs.  A GOTO or CONT statement
        can be used to resume execution.  An error inside a named
        SUB subroutine cannot be resumed from or CONTinued.

    sub NAME ( VAR { , VAR ... } }

        Subroutine entry.  May be called by a CALL statement or
        by NAME. A SUB subroutine must be exited by a RETURN or
        END SUB statement.  There should be only one RETURN or
        END SUB statement per SUB subroutine.  The variables in
        the VAR list become local variables. String and numeric
        arguments are passed by value; array arguments must be
        pre-dimensioned and are passed by reference.

        Example:
            110  x = foo (7, j) : rem Pass 7 and j by value.
            ...
            2000 sub foo (x,y,z) : rem z is a local variable
            2010   print x       : rem prints 7 the first time
            2090 return (y+1)    : rem also restores x,y,z


    select case EXPR

        Multi-way branch.  Executes the statements after the CASE
        statement which matches the SELECT CASE expression, then
        skips to the END SELECT statement.  If these is no match,
        and a CASE ELSE statement is present, then execution
        defaults to the statements following the CASE ELSE.

        Example:
            200 select case x
            210   case 2
            ...
            230   case 3, 4
            ...
            270   case else
            ...
            290 end select


    dim VAR( d { , d { , d } } ) { , VAR( d { , d { , d } } ) }

        Dimension an array or list of arrays (string or numeric).
        A maximum of 4 dimensions can be used. The maximum
        dimension size is limited by available memory. Legal
        array subscripts are from 0 up and including the
        dimension specified; d+1 elements are allocated.  All
        arrays must be dimensioned before use.

        Example:
            10 dim a(10)
            20 for i=0 to 10
            30   a(i) = i^2
            40 next i
            50 print a(5) : rem should print 25

    dim VAR { ( INT ) } as TYPENAME

        Create a record using a previously defined structure
        definition. Optionally create an array of records.

    type TYPENAME

        Create a structure definition type.  Each field
        requires a separate line.  Legal types are string,
        integer and double.  The definition must conclude with
        an END TYPE statement.  Use the DIM AS statement to
        create records with the specified structure.

        Example:
            300 type person
            310   name as string * 32 : rem 31 max length
            320   age as integer
            330   weight as double
            340 end type
            400 dim friend1 as person
            410 friend1.name = "bill"
            420 print friend1.name, friend1.age


    read VAR { , VAR }

        Read data from the DATA statements contained in the
        program. List items can be either string or numeric
        variables. Reading past the end the last DATA statement
        generates an error.

    data ITEM { , ITEM }

        DATA statements contain the data used in the READ
        statements. Items must be separated by commas.  The
        items may be either numeric or string expressions,
        corresponding to the type of variable being read.
        Reading the wrong kind of object produces a "Type
        mismatch" error.

    restore { LINENUM }

        The RESTORE statement causes the next READ to use the
        first DATA statement in the program.  If a LINENUM is
        given then the DATA statement on or after that
        particular line is used next.

    rem or "`"

        A remark or comment statement.  Ignored by the program
        during execution, however a REM statement can be the
        target of a GOTO or GOSUB.

    open STRINGEXPR for { input|output|append } as # FNUM

        Open a file. The { input|output|append } parameter
        specifies whether the file is to be read, written or
        appended.  If STRINGEXPR is "stdin" for input or
        "stdout" for output then the console will be used
        instead of a file.  A "file not found" error will
        occur if a non-existant file is specified in an OPEN
        for input statement.

    close # FNUM

        Close a file. Releases the file descriptor and flushes
        out all stored data.

    def fnNAME ( VAR { , VAR } ) = EXPR

        Define a user definable function.

        Example:
            10 def fnplus(x,y) = x+y
            20 print fnplus(3,5) : rem prints 8

    { let } mid$( STRINGVAR, EXPR1, EXPR2 ) = STRINGEXPR

        Insert STRINGEXPR into STRINGVAR starting at EXPR1
        for character length EXPR2.

    exec(STRINGEXPR)

        Executes STRINGEXPR as a statement or command.
        e.g. exec("print " + "x") will print the value of x.

    poke ADDR_EXPR, DATA_EXPR

        Poke a byte into a memory location. Unreasonable
        addresses can cause bus-errors.

    push VAR { , VAR ... }

        Pushes one or more expressions or variables onto an
        internal stack.  Expressions can be returned using the
        POP function; variables can be returned by using the
        POP statement.

    pop VAL

        POP statement (see also POP function). Pops VAL
        variables off the internal stack, restoring the value
        of those variables to their pushed values.

    NUMERIC FUNCTIONS

    sgn(VAL)

        Returns the sign of the parameter value.  Returns 1 if
        the value is greater than zero , zero if equal to zero.
        -1 if negative.

    abs(x)

        Returns the absolute value of x.

    int(x)

        Returns the integer value of x.  Truncates toward zero.

    sqr(x)

        Returns the square root of x.

    log(x)

        Returns the natural logarithm of x.

    exp(x)

        Returns e^x. e=2.7182818...

    sin(x)
    cos(x)
    atn(x)

        Trigonometric functions: sin, cosine and arctangent.

    pi

        Returns pi, 3.14159265358979323...

    rnd ( EXPR )

        Returns a random number between 0 and int(EXPR)-1 inclusive.
        If EXPR is 1, then returns a fraction between 0 and 1.
        If EXPR is negative then EXPR seeds the random number
        generator.

    randomize EXPR

        Seeds the random number generator with the integer EXPR.

    len(STRINGEXPR)

        Returns the length of the string STRINGEXPR.

    val(STRINGEXPR)

        Value of the expression contained in STRINGEXPR.
        STRINGEXPR may be a string literal, variable, function,
        or expression.

        For example, VAL("1+sqr(4)") yields 3.

    asc(STRINGEXPR)

        Returns the ascii code for the first character of
        STRINGEXPR.  A null string returns zero.

    instr(a$, b$ { , VAL } )

        Returns the position of the substring b$ in the string a$
        or returns a zero if b$ is not a substring.
        VAL is an optional starting position in a$

    eof(FILENUM)

        Returns true if the file specified by FILENUM has reached
        the end of the file.

    pop

        POP function (see also POP statement). Pops one variable
        value off the stack and returns that value (string or
        numeric).

        (POP can be used as either a statement (with a
        parameter) or a function (no parameter). Note that the
        POP function, unlike the POP statement, does not
        restore the value of the variable pushed, but only
        returns the pushed value.  This use of the POP
        statement is different from the Applesoft usage.)

    peek( ADDR { , VAL } )

        Returns the value of the byte in memory at address ADDR.
        If VAL is 2 or 4, returns the value of the 16-bit or
        32-bit word respectively (if correctly aligned).
        If VAL is 8, returns the value of the numeric variable
        located at ADDR.  peek(varptr(x),8) equals x.

    varptr( VAR | STRINGVAR )

        Returns the memory address of a variable.

    erl

        Returns the line number of the last error.  Zero if the
        error was in immediate mode.  The variable errorstatus$
        gives the error type.

    timer

        Returns a numeric value of elapsed of seconds from the
        computers internal clock.


    STRING FUNCTIONS

    x$ + y$

        String concatenation.  Result must be 254 characters or less.

    chr$(VAL)

        Returns the ascii character corresponding to the value
        of VAL.

    str$( VAL { , EXPR } )

        Returns a string representation corresponding to VAL.
        If EXPR is present then the string is padded to that
        length.

    inkey$

        Return one character from the keyboard if input is
        available. Returns a zero length string { "" } if no
        keyboard input is available.  Non-blocking.  Can be used
        for keyboard polling.

    input$( EXPR { , FILENUM } )

        Returns EXPR characters from file FILENUM. If f is not
        present then get input from the console keyboard.

    mid$( a$, i { , j } )

        Returns a substring of a$ starting at the i'th
        positions and j characters in length. If the second
        parameter is not specified then the substring is taken
        from the start position to the end of a$.

    right$(a$, EXPR )

        Returns the right EXPR characters of a$.

    left$(a$, EXPR )

        Returns the left EXPR characters of a$.

    field$( STRINGVAL, VAL { , STRINGVAL } )

        Returns the n-th field of the first string.  If the
        optional string is present then use the first character
        of that string as the field separator.  The default
        separator is a space.  Similar to UNIX 'awk' fields.

        e.g.  field$("11 22 33 44", 3)  returns  "33"

    hex$( VAL { , EXPR } )
    bin$( VAL { , EXPR } )

        Returns the hexadecimal or binary string representation
        corresponding to VAL.  If EXPR is present then the
        string is padded with zeros to make it that length.

    lcase$( STRINGVAL )

        Returns STRINGVAL in all lower case characters.

    errorstatus$

        Returns the error message for the last error.


    OPERATORS

    The following mathematical operators  are available:

        ^    exponentiation
        *    multiplication
        /    division
        mod    remainder
        +    addition
        -    subtraction

    logical operators: (any non-zero value is true)

            not    logical not

    bitwise operators:

            and    bitwise and
            or    bitwise or
            xor    bitwise exclusive-or

    comparison operators:

            <=    less than or equal
            <>    not equal to
            >=    greater than or equal
            =    equal
            >    greater than
            <    less than

    x$=y$, x$<y$, x$>y$, x$<=y$, x$>=y$, x$<>y$

        String comparisons; result is 1 if true, 0 if false.

    Operator precedence (highest to lowest):

        ( )
        not -{unary_minus} functions
        ^
        * / mod
        + -
        = < > <= >= <>
        and
        or xor


    UNIX commands and functions:

    sys( STRINGVAL )

        UNIX system call.  The string parameter is given to
        the shell as a command.

    argv$
        Returns the UNIX shell command line arguments.


    Macintosh commands:

    gotoxy VAL, VAL

        Set the horizontal and vertical location of the
        text output cursor.  (0,0) is the upper left corner.

    moveto VAL, VAL

        Sets the (x,y) location of the graphics pen.

    lineto VAL, VAL

        Draws a line from the current pen location to location
        (x,y) in the graphics window.

    window x, y, char_cols, char_lines

        Change the text console window position and size.

    morse STRINGVAL { , VAL, VAL, VAL, VAL }

        Plays morse code through the speaker.
        The parameters are { dot-speed-wpm, volume{0..100},
        word-speed-wpm, frequency_cps }

    sound VAL, VAL, VAL

        The parameters are
        { frequency_cps, seconds_duration, volume{0..100} }

    say STRINGVAL

        Speaks STRINGVAL if the Speech Manager Extension is
        resident.  Try "say a$,200,46,1" for faster speech.

    open "SFGetFile" for input  as #FNUM
    open "SFPutFile" for output as #FNUM

        Puts up a standard file dialog for the file name.

    files { STRINGVAL }

        Displays a listing of files in the named or current
        directory.

    Macintosh functions:

    fre
        Returns the amount of memory left for program use.

    date$
        Returns a string corresponding to the current date.

    time$
        Returns a string corresponding to the current time.

    pos(VAL)

        Returns the horizontal position of the text cursor.
        If VAL is negative returns the vertical position.

    errorstatus$

        Also returns the full path name of the program and
        files opened by SFGetFile. (under System 7 and only
        if the name fits in a string variable)


    Macintosh menu items:

    Open or <cmd>O     will put up a dialog to allow selection
            of a program file to load.  Basic Program file
            names must end with a ".bas" suffix.

    Copy        will allow copying picts from the graphics
            window.

    <cmd>.         Command-period will stop program execution.

    Print        Print graphics window if it's the front most window.
            Only the graphics window can be printed.


    CONVENTIONS

    EXPR        any expression that evaluates to a numeric value.
    STRINGEXPR    a string expression.
    VAR        a numeric variable.
    STRINGVAR    a string variable. Name must end with a "$".
    INTEGERVAR    a 16-bit variable. Name must end with a "%".

    All program lines must begin with a line number.  A line number
    entered by itself will delete that program line. Using spaces
    (indentation) between the line number and program statements is
    legal.  Line numbers can be between 1 and 2147483647.

    Hexadecimal numbers can be entered by preceding them with
    a "0x" as in 0x02ae, or by "&h" as in &h0172.

    Multiple statements may be given on one line, separated by
    colons:

        10 INPUT X : PRINT X : STOP


    DIAGNOSTICS

    Some errors can be caught by the user program using the "on error
    goto" command. If no error trapping routine has been supplied
    then program execution is terminated and a message is printed
    with the corresponding line number.

    Graphics may require that the preferred memory requirements be
    increased using the Finder "Get Info" dialog box.


    AUTHORS

    David Gillespie wrote basic.p 1.0 and the p2c lib.
    Ron Nicholson ([e-mail]) added file i/o, graphics and
    did the Unix, Macintosh and PowerMac port.  (1990-1995Nov)


    BUGS

    Many.

    Can't CONTinue from an error inside a named SUB subroutine.

    PRINT USING format string doesn't recognize comma's or underscores.

    Integer VARs, like i%, don't work in FOR-NEXT statements. Integer
    arrays can only have a dimension of one and will only work in
    assignment (LET) statements.  All arithmetic on integer variables
    is done using floating point arithmetic.

    Macintosh screen editing will only recognise the last line modified
    before a RETURN or ENTER key.  The EDIT command and screen editing
    are incompatible.

    There are several undocumented graphics and sprite commands
    and keywords in the Macintosh port.  See the accompanying
    README and quick-ref files.


    Portions Copyright (C) 1989 Dave Gillespie
    Copyright (C) 1994 Ronald H. Nicholson, Jr., All rights reserved.
    "Applesoft" is a trademark of Apple Computer, Inc., etc.